home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2001 May / SGI Freeware 2001 May - Disc 3.iso / dist / fw_openssl.idb / usr / freeware / lib / openssl / doc / INSTALL.z / INSTALL
Encoding:
Text File  |  2001-01-10  |  10.5 KB  |  279 lines
  1.  
  2.  INSTALLATION ON THE UNIX PLATFORM
  3.  ---------------------------------
  4.  
  5.  [Installation on Windows, OpenVMS and MacOS (before MacOS X) is described
  6.   in INSTALL.W32, INSTALL.VMS and INSTALL.MacOS.]
  7.  
  8.  To install OpenSSL, you will need:
  9.  
  10.   * Perl 5
  11.   * an ANSI C compiler
  12.   * a supported Unix operating system
  13.  
  14.  Quick Start
  15.  -----------
  16.  
  17.  If you want to just get on with it, do:
  18.  
  19.   $ ./config
  20.   $ make
  21.   $ make test
  22.   $ make install
  23.  
  24.  [If any of these steps fails, see section Installation in Detail below.]
  25.  
  26.  This will build and install OpenSSL in the default location, which is (for
  27.  historical reasons) /usr/local/ssl. If you want to install it anywhere else,
  28.  run config like this:
  29.  
  30.   $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl
  31.  
  32.  
  33.  Configuration Options
  34.  ---------------------
  35.  
  36.  There are several options to ./config (or ./Configure) to customize
  37.  the build:
  38.  
  39.   --prefix=DIR  Install in DIR/bin, DIR/lib, DIR/include/openssl.
  40.             Configuration files used by OpenSSL will be in DIR/ssl
  41.                 or the directory specified by --openssldir.
  42.  
  43.   --openssldir=DIR Directory for OpenSSL files. If no prefix is specified,
  44.                 the library files and binaries are also installed there.
  45.  
  46.   rsaref        Build with RSADSI's RSAREF toolkit (this assumes that
  47.                 librsaref.a is in the library search path).
  48.  
  49.   no-threads    Don't try to build with support for multi-threaded
  50.                 applications.
  51.  
  52.   threads       Build with support for multi-threaded applications.
  53.                 This will usually require additional system-dependent options!
  54.                 See "Note on multi-threading" below.
  55.  
  56.   no-shared     Don't try to create shared libraries.
  57.  
  58.   shared        In addition to the usual static libraries, create shared
  59.                 libraries on platforms where it's supported.  See "Note on
  60.                 shared libraries" below.
  61.  
  62.   no-asm        Do not use assembler code.
  63.  
  64.   386           Use the 80386 instruction set only (the default x86 code is
  65.                 more efficient, but requires at least a 486).
  66.  
  67.   no-<cipher>   Build without the specified cipher (bf, cast, des, dh, dsa,
  68.                 hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha).
  69.                 The crypto/<cipher> directory can be removed after running
  70.                 "make depend".
  71.  
  72.   -Dxxx, -lxxx, -Lxxx, -fxxx, -Kxxx These system specific options will
  73.                 be passed through to the compiler to allow you to
  74.                 define preprocessor symbols, specify additional libraries,
  75.                 library directories or other compiler options.
  76.  
  77.  
  78.  Installation in Detail
  79.  ----------------------
  80.  
  81.  1a. Configure OpenSSL for your operation system automatically:
  82.  
  83.        $ ./config [options]
  84.  
  85.      This guesses at your operating system (and compiler, if necessary) and
  86.      configures OpenSSL based on this guess. Run ./config -t to see
  87.      if it guessed correctly. If you want to use a different compiler, you
  88.      are cross-compiling for another platform, or the ./config guess was
  89.      wrong for other reasons, go to step 1b. Otherwise go to step 2.
  90.  
  91.      On some systems, you can include debugging information as follows:
  92.  
  93.        $ ./config -d [options]
  94.  
  95.  1b. Configure OpenSSL for your operating system manually
  96.  
  97.      OpenSSL knows about a range of different operating system, hardware and
  98.      compiler combinations. To see the ones it knows about, run
  99.  
  100.        $ ./Configure
  101.  
  102.      Pick a suitable name from the list that matches your system. For most
  103.      operating systems there is a choice between using "cc" or "gcc".  When
  104.      you have identified your system (and if necessary compiler) use this name
  105.      as the argument to ./Configure. For example, a "linux-elf" user would
  106.      run:
  107.  
  108.        $ ./Configure linux-elf [options]
  109.  
  110.      If your system is not available, you will have to edit the Configure
  111.      program and add the correct configuration for your system. The
  112.      generic configurations "cc" or "gcc" should usually work on 32 bit
  113.      systems.
  114.  
  115.      Configure creates the file Makefile.ssl from Makefile.org and
  116.      defines various macros in crypto/opensslconf.h (generated from
  117.      crypto/opensslconf.h.in).
  118.  
  119.   2. Build OpenSSL by running:
  120.  
  121.        $ make
  122.  
  123.      This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the
  124.      OpenSSL binary ("openssl"). The libraries will be built in the top-level
  125.      directory, and the binary will be in the "apps" directory.
  126.  
  127.      If "make" fails, look at the output.  There may be reasons for
  128.      the failure that isn't a problem in OpenSSL itself (like missing
  129.      standard headers).  If it is a problem with OpenSSL itself, please
  130.      report the problem to <openssl-bugs@openssl.org> (note that your
  131.      message will be forwarded to a public mailing list).  Include the
  132.      output of "make report" in your message.
  133.  
  134.      [If you encounter assembler error messages, try the "no-asm"
  135.      configuration option as an immediate fix.]
  136.  
  137.      Compiling parts of OpenSSL with gcc and others with the system
  138.      compiler will result in unresolved symbols on some systems.
  139.  
  140.   3. After a successful build, the libraries should be tested. Run:
  141.  
  142.        $ make test
  143.  
  144.      If a test fails, look at the output.  There may be reasons for
  145.      the failure that isn't a problem in OpenSSL itself (like a missing
  146.      or malfunctioning bc).  If it is a problem with OpenSSL itself,
  147.      try removing any compiler optimization flags from the CFLAGS line
  148.      in Makefile.ssl and run "make clean; make". Please send a bug
  149.      report to <openssl-bugs@openssl.org>, including the output of
  150.      "make report".
  151.  
  152.   4. If everything tests ok, install OpenSSL with
  153.  
  154.        $ make install
  155.  
  156.      This will create the installation directory (if it does not exist) and
  157.      then the following subdirectories:
  158.  
  159.        certs           Initially empty, this is the default location
  160.                        for certificate files.
  161.        man/man1        Manual pages for the 'openssl' command line tool
  162.        man/man3        Manual pages for the libraries (very incomplete)
  163.        misc            Various scripts.
  164.        private         Initially empty, this is the default location
  165.                        for private key files.
  166.  
  167.      If you didn't choose a different installation prefix, the
  168.      following additional subdirectories will be created:
  169.  
  170.        bin             Contains the openssl binary and a few other 
  171.                        utility programs. 
  172.        include/openssl Contains the header files needed if you want to
  173.                        compile programs with libcrypto or libssl.
  174.        lib             Contains the OpenSSL library files themselves.
  175.  
  176.      Package builders who want to configure the library for standard
  177.      locations, but have the package installed somewhere else so that
  178.      it can easily be packaged, can use
  179.  
  180.        $ make INSTALL_PREFIX=/tmp/package-root install
  181.  
  182.      (or specify "--install_prefix=/tmp/package-root" as a configure
  183.      option).  The specified prefix will be prepended to all
  184.      installation target filenames.
  185.  
  186.  
  187.   NOTE: The header files used to reside directly in the include
  188.   directory, but have now been moved to include/openssl so that
  189.   OpenSSL can co-exist with other libraries which use some of the
  190.   same filenames.  This means that applications that use OpenSSL
  191.   should now use C preprocessor directives of the form
  192.  
  193.        #include <openssl/ssl.h>
  194.  
  195.   instead of "#include <ssl.h>", which was used with library versions
  196.   up to OpenSSL 0.9.2b.
  197.  
  198.   If you install a new version of OpenSSL over an old library version,
  199.   you should delete the old header files in the include directory.
  200.  
  201.   Compatibility issues:
  202.  
  203.   *  COMPILING existing applications
  204.  
  205.      To compile an application that uses old filenames -- e.g.
  206.      "#include <ssl.h>" --, it will usually be enough to find
  207.      the CFLAGS definition in the application's Makefile and
  208.      add a C option such as
  209.  
  210.           -I/usr/local/ssl/include/openssl
  211.  
  212.      to it.
  213.  
  214.      But don't delete the existing -I option that points to
  215.      the ..../include directory!  Otherwise, OpenSSL header files
  216.      could not #include each other.
  217.  
  218.   *  WRITING applications
  219.  
  220.      To write an application that is able to handle both the new
  221.      and the old directory layout, so that it can still be compiled
  222.      with library versions up to OpenSSL 0.9.2b without bothering
  223.      the user, you can proceed as follows:
  224.  
  225.      -  Always use the new filename of OpenSSL header files,
  226.         e.g. #include <openssl/ssl.h>.
  227.  
  228.      -  Create a directory "incl" that contains only a symbolic
  229.         link named "openssl", which points to the "include" directory
  230.         of OpenSSL.
  231.         For example, your application's Makefile might contain the
  232.         following rule, if OPENSSLDIR is a pathname (absolute or
  233.         relative) of the directory where OpenSSL resides:
  234.  
  235.         incl/openssl:
  236.             -mkdir incl
  237.             cd $(OPENSSLDIR) # Check whether the directory really exists
  238.             -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl
  239.  
  240.         You will have to add "incl/openssl" to the dependencies
  241.         of those C files that include some OpenSSL header file.
  242.  
  243.      -  Add "-Iincl" to your CFLAGS.
  244.  
  245.      With these additions, the OpenSSL header files will be available
  246.      under both name variants if an old library version is used:
  247.      Your application can reach them under names like <openssl/foo.h>,
  248.      while the header files still are able to #include each other
  249.      with names of the form <foo.h>.
  250.  
  251.  
  252.  Note on multi-threading
  253.  -----------------------
  254.  
  255.  For some systems, the OpenSSL Configure script knows what compiler options
  256.  are needed to generate a library that is suitable for multi-threaded
  257.  applications.  On these systems, support for multi-threading is enabled
  258.  by default; use the "no-threads" option to disable (this should never be
  259.  necessary).
  260.  
  261.  On other systems, to enable support for multi-threading, you will have
  262.  to specify at least two options: "threads", and a system-dependent option.
  263.  (The latter is "-D_REENTRANT" on various systems.)  The default in this
  264.  case, obviously, is not to include support for multi-threading (but
  265.  you can still use "no-threads" to suppress an annoying warning message
  266.  from the Configure script.)
  267.  
  268.  
  269.  Note on shared libraries
  270.  ------------------------
  271.  
  272.  For some systems, the OpenSSL Configure script knows what is needed to
  273.  build shared libraries for libcrypto and libssl.  On these systems,
  274.  the shared libraries are currently not created by default, but giving
  275.  the option "shared" will get them created.  This method supports Makefile
  276.  targets for shared library creation, like linux-shared.  Those targets
  277.  can currently be used on their own just as well, but this is expected
  278.  to change in future versions of OpenSSL.
  279.